<?php
/** 
 * 
 *
 * @package api
 * @subpackage collections
 * @author $Author$
 * @version $Id: Comparator.php 14 2006-11-28 22:05:19Z rdff3 $
 */
/**
 *
 */
require_once( "lang/Object.php" );
require_once( "lang/ClassCastException.php" );
 
/**
 * Interface Comparator
 *
 * A comparison function, which imposes a total ordering on some collection of objects. Comparators can be passed to a sort 
 * method (such as Collections.sort) to allow precise control over the sort order. Comparators can also be used to control the 
 * order of certain data structures (such as TreeSet or TreeMap).
 * 
 * The ordering imposed by a Comparator c on a set of elements S is said to be consistent with equals if and only if 
 * (compare((Object)e1, (Object)e2)==0) has the same boolean value as e1.equals((Object)e2) for every e1 and e2 in S.
 * 
 * Caution should be exercised when using a comparator capable of imposing an ordering inconsistent with equals to order a 
 * sorted set (or sorted map). Suppose a sorted set (or sorted map) with an explicit Comparator c is used with elements 
 * (or keys) drawn from a set S. If the ordering imposed by c on S is inconsistent with equals, the sorted set (or sorted map) 
 * will behave "strangely." In particular the sorted set (or sorted map) will violate the general contract for set (or map), 
 * which is defined in terms of equals.
 * 
 * For example, if one adds two keys a and b such that (a.equals((Object)b) && c.compare((Object)a, (Object)b) != 0) to a 
 * sorted set with comparator c, the second add operation will return false (and the size of the sorted set will not increase) 
 * because a and b are equivalent from the sorted set's perspective.
 * 
 * Note: It is generally a good idea for comparators to implement java.io.Serializable, as they may be used as ordering methods 
 * in serializable data structures (like TreeSet, TreeMap). In order for the data structure to serialize successfully, the 
 * comparator (if provided) must implement Serializable.
 * 
 * For the mathematically inclined, the relation that defines the total order that a given comparator c imposes on a given set 
 * of objects S is:
 * <pre>
 *        {(x, y) such that c.compare((Object)x, (Object)y) <= 0}.
 * </pre>
 * The quotient for this total order is:
 * <pre>
 *        {(x, y) such that c.compare((Object)x, (Object)y) == 0}.
 * </pre>
 * It follows immediately from the contract for compare that the quotient is an equivalence relation on S, and that the 
 * natural ordering is a total order on S. When we say that the ordering imposed by c on S is consistent with equals, we 
 * mean that the quotient for the natural ordering is the equivalence relation defined by the objects' equals(Object) 
 * method(s):
 * <pre>
 *        {(x, y) such that x.equals((Object)y)}.
 * </pre>
 * This interface is a member of the PHP Collections Framework. 
 *
 * @package api
 * @subpackage collections
 * @author $Author$
 * @version $Id: Comparator.php 14 2006-11-28 22:05:19Z rdff3 $
 */
interface Comparator {
	
	/**
	 * Compares its two arguments for order.
	 *
	 * Compares its two arguments for order. Returns a negative integer, zero, or a positive integer as the first argument is 
	 * less than, equal to, or greater than the second.
	 * 
	 * The implementor must ensure that sgn(compare(x, y)) == -sgn(compare(y, x)) for all x and y. (This implies that 
	 * compare(x, y) must throw an exception if and only if compare(y, x) throws an exception.)
	 *
	 * The implementor must also ensure that the relation is transitive: ((compare(x, y)>0) && (compare(y, z)>0)) implies 
	 * compare(x, z)>0.
	 * 
	 * Finally, the implementer must ensure that compare(x, y)==0 implies that sgn(compare(x, z))==sgn(compare(y, z)) for 
	 * all z.
	 * 
	 * It is generally the case, but not strictly required that (compare(x, y)==0) == (x.equals(y)). Generally speaking, 
	 * any comparator that violates this condition should clearly indicate this fact. The recommended language is "Note: 
	 * this comparator imposes orderings that are inconsistent with equals." 
	 * 
	 * @param Object $o1 the first object to be compared
	 * @param Object $o2 the second object to be compared
	 * @returns int a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater 
	 * 		than the second.
	 * @throws {@link ClassCastException} - if the arguments' types prevent them from being compared by this Comparator.
	 */
	public function compare( Object $o1, Object $o2 );
	
	/**
	 * Indicates whether some other object is "equal to" this Comparator.
	 * 
	 * Indicates whether some other object is "equal to" this Comparator. This method must obey the general contract of 
	 * Object.equals(Object). Additionally, this method can return true only if the specified Object is also a comparator 
	 * and it imposes the same ordering as this comparator. Thus, comp1.equals(comp2) implies that sgn(comp1.compare(o1,
	 * o2))==sgn(comp2.compare(o1, o2)) for every object reference o1 and o2.
	 *
	 * Note that it is always safe not to override Object.equals(Object). However, overriding this method may, in some cases, 
	 * improve performance by allowing programs to determine that two distinct Comparators impose the same order. 
	 *
	 * @param Object $obj the reference object with which to compare.
	 * @returns boolean true only if the specified object is also a comparator and it imposes the same ordering as this comparator.
	 */
	public function equals( Object $obj );  
}


?>